docs(agents): stop telling authors to hand-edit generated CHANGELOG.md - #14802
Merged
Conversation
Post-task checklist item 6 read "Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural", which contradicts the same file 34 lines above: the changeset section states the changeset body "ships to consumers as `CHANGELOG.md` inside the npm package". `CHANGELOG.md` is generated output, written by the changesets release step from the entries item 3 already requires, so item 6 was directing the author to hand-edit a generated artifact that the next Version Packages run overwrites or collides with. Drop the `CHANGELOG.md` half; keep `ROADMAP.md`, which may genuinely be hand-maintained and is not in question here. Byte-negative on one line (-17 bytes), no line added or re-wrapped: the file is at its ratchet ceiling with headroom 0. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
github-actions
Bot
added
size/xs
documentation
os-litant
added
the
skip-changeset
Claude
os-zhuang
approved these changes
Sep 3, 2026
os-zhuang
marked this pull request as ready for review
September 3, 2026 04:55
os-zhuang
enabled auto-merge
September 3, 2026 04:55
Contributor
This was referenced Sep 3, 2026
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #14792
Post-task checklist item 6 in
AGENTS.mdtold the author to hand-editCHANGELOG.md. That file is generated output. This drops theCHANGELOG.mdhalf of the line and keepsROADMAP.md.Before / after
AGENTS.md:1154Before:
After:
Why
The same file says the opposite about
CHANGELOG.mdthirty-four lines above. AtAGENTS.md:1120, inside checklist item 3, the changeset rule states that the changeset body "ships to consumers asCHANGELOG.mdinside the npm package and is what an upgrading agent greps after the tombstone error". That makesCHANGELOG.mdthe output — written by the changesets release step from the.changeset/*.mdentries item 3 already requires.Item 6 treated the same file as an input. A contributor who obeyed it either hand-edited a generated artifact that the next
Version Packagesrun overwrites or collides with, or read the two lines together and concluded the file contradicts itself on its most-traversed workflow. Nothing is lost by the trim: the changeset obligation is item 3, and it is unchanged here.Neither reading of the name survives, which is what makes the trim safe rather than a judgement call. Item 6 could have meant the per-package
CHANGELOG.mdfiles or the repo-root one, so both were checked:packages/core/CHANGELOG.mdand its siblings carry changeset-emitted release sections keyed by commit hash.CHANGELOG.mddisclaims hand-editing in its own header: the update history "is maintained in three layers rather than by hand-editing this file" — per-package detail "generated by [changesets] from the.changeset/entries every PR adds", the curated per-major pages undercontent/docs/releases/, and this file "retained for its historical entries."So there is no
CHANGELOG.mdin this repo that item 6 could have legitimately directed a PR author to update by hand.ROADMAP.mdis untouched and not in question, and the surviving half is not vacuous: the file exists at the repo root and its history shows real hand edits. This PR makes no claim about whether that obligation should stand.Arithmetic
AGENTS.mdis at its line-ratchet ceiling, so the edit adds no line and re-wraps nothing.wc -l)wc -c)grep -c 'CHANGELOG.md' AGENTS.md:1120,:1154):1120only)Byte-negative on one line, so nothing is paid same-file.
git diff --statis1 file changed, 1 insertion(+), 1 deletion(-).Scope held
Untouched, deliberately: the
ROADMAP.mdhalf of item 6, checklist item 3, and the changeset section at:1116-1122— that region is being corrected by PR #14789, and a second PR editing it would be a merge conflict on a governed file for no gain. The hunk here at:1154is disjoint from that one.One argument recorded for the merging maintainer rather than acted on: a reading exists under which item 6 should be deleted outright rather than trimmed, on the grounds that
ROADMAP.mdupdates are not obviously a per-PR obligation either. That is a scope decision, not this card's, so the line is trimmed as ruled and the argument is left here.Gates
All run at head
9596a42386, exit codes captured by redirect before any pipe; each verdict below is the gate's own printed line.pnpm check:pm-skill-ratchetAGENTS.md is 1162 lines (ceiling 1162; headroom 0).·AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0).· self-test 111 cases passpnpm check:pm-governed-prose2 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.pnpm check:pm-skill-id-lint23 file(s) clean (pattern /#[0-9]{3,}/g).pnpm check:nul-bytesOK (scanned 8064 text file(s) -- 8064 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).pnpm check:corpus-claim-driftOK, no new claim sites beside a pinned spelling.pnpm check:required-contexts6 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).node scripts/check-required-contexts.mjspnpm check:agent-test-spellingpnpm check:docs-audit-scopedocs-accuracy-audit scope is in sync with content/docs/: 190 hand-written doc(s)pnpm check:pm-governed-mergeslive: the real generator declared 9 output(s) and certified this treeThe family list was re-derived after the last edit, not taken from the dispatch:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commandsresolved its--repoassertion against this checkout's origin, derived the change set from git as 1 path (AGENTS.md, committed 1 / working tree 0 / untracked 0, three-dot against merge basefc648a256) and emitted 8 commands. All 8 ran; the two dispatch-named gates outside that union (check:nul-bytes,check:corpus-claim-drift) ran as well, so the set above is a superset.ESLint
Not run repo-wide; narrowed, and the narrowing is a measurement rather than a skip:
eslint.config.mjsand not guessed. Everyfiles:selector in the config is a JS/TS extension glob (**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}and narrower variants;COMMENT_SWALLOW_FILESat:785is that same glob).grep -cin 'markdown|[.]md' eslint.config.mjsreturns 0 — no markdown processor, no.mdselector anywhere. Confirmed through ESLint's own API:isPathIgnored('AGENTS.md')istrueandcalculateConfigForFile('AGENTS.md')yields no rules, against a positive control (eslint.config.mjsitself resolves 2 rules), so the API call is not vacuously quiet.--format json.pnpm exec eslint AGENTS.md --no-inline-config --format jsongiveserrorCount: 0, warningCount: 1, the one warning beingruleId: null/File ignored because no matching configuration was supplied— zero rule results, because the file is outside the population.parserOptions.project, no typed rules, stated ateslint.config.mjs:325-332with its own measured positive control. With no cross-file type program there is no mechanism by which an edit in one file moves a verdict on a file it does not touch, and this diff is one Markdown line in a file ESLint does not lint at all.A full
pnpm linttherefore measures the same nothing this narrowing measured.Changeset
Labelled
skip-changeset, route 2 ofscripts/check-empty-changeset.mjs's own enumeration: "It releases nothing (.github/,.claude/,skills/,docs/,content/,examples/, tests-only, and the like) -- delete the changeset and apply the 'skip-changeset' label". This diff is one line of the repo-root instruction file; nopackages/**source is touched and nothing publishes from any package. Per that script, the label is a gate-level exemption that produces no input forchangesets/action— the shape an empty-frontmatter changeset would have broken.Landing
Draft, and it stays draft — governed
AGENTS.md, human merge is the review record. Not flipped ready, not queued, no auto-merge armed, no reviewers requested.🤖 Generated with Claude Code
https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1